home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 001-010 / amok08 / iff8svxload / iff8svxload.readme < prev    next >
Text File  |  1993-11-04  |  8KB  |  221 lines
  1.  
  2.  
  3.                          IFF8SVXLoad
  4.                       ==================
  5.  
  6.        © 1988 by Fridtjof Siebert
  7.                  Nobileweg 67
  8.                  D-7000 Stuttgart-40
  9.  
  10.  
  11.     IFF8SVXLoad exports some procedures to load and play digitized sounds.
  12.  
  13.  
  14.              Load a Sampled Sound:
  15.            -------------------------
  16.  
  17.   PROCEDURE Read8SVX(Name: ARRAY OF CHAR;
  18.                      MaxChunkSize: LONGCARD;
  19.                      ChipMem: BOOLEAN):
  20.                      IFF8SVXInfoPtr;
  21.  
  22.      This procedure loads the sound named Name. It's data is saved in
  23.      blocks that are MaxChunkSize big. A MaxChunkSize of 0 lets
  24.      Read8SVX() allocate a single memorychunk for each octave. This
  25.      can cause problems with big sounds. ChipMem specifies whether the
  26.      blocks are in ChipMem. If so they can be played easier, because
  27.      there's no need for doublebuffering and to copy them to chipmem.
  28.  
  29.      Read8SVX()'s result is a pointer to an IFF8SVXLoad.IFF8SVXInfo. This
  30.      Record contains all loaded data. In case of any error, the result
  31.      will be NIL. More information about the error can be got via the
  32.      variable IFF8SVXLoad.IFF8SVXError.
  33.  
  34.      There can be some problems when you want to load a long sound and you
  35.      have selected a small MaxChunkSize and your Stack is not especially
  36.      big. There can occur some strange errors like Address, Stack Overflow
  37.      and even the Guru!!!
  38.  
  39.  
  40.              Deallocate Sampled Sound's Memory:
  41.            --------------------------------------
  42.  
  43.   PROCEDURE Dealloc8SVX(Info:IFF8SVXInfoPtr);
  44.  
  45.  
  46.      Dealloc8SVX() frees Info's Memory.
  47.  
  48.  
  49.                Open Audio-Device:
  50.              ------------------------
  51.  
  52.      To play a sound, you first have to open the Audio-Device. This is
  53.      done by the procedure OpenAudio:
  54.  
  55.   PROCEDURE OpenAudio(Channels: CARDINAL; Priority: Byte): BOOLEAN;
  56.  
  57.      Channels specifies how many channels to allocate. There are up to 4
  58.      channels possible. Priority sets the allocation priority, that ranges
  59.      from -128 (lowest) to 127 (highest priority).
  60.  
  61.      OpenAudio()'s result is TRUE, if successful and FALSE if any error
  62.      occured. Information on the error can be got from IFF8SVXError.
  63.  
  64.  
  65.              Play sampled sounds:
  66.            ------------------------
  67.  
  68.      Having opened the audio-device, you can play the loaded sound:
  69.  
  70.   PROCEDURE PlaySample(Info:    IFF8SVXInfoPtr;
  71.                        Octave:  INTEGER;
  72.                        Repeat:  CARDINAL;
  73.                        Channel: CARDINAL): BOOLEAN;
  74.  
  75.      Info is the pointer Read8SVX() gave you. Octave selects the octave of
  76.      the sound, you want to play. It can be a value between 0 and 7. Apart
  77.      from instruments, sampled sounds have normally just one octave (#0).
  78.      Repeat selects how often to repeat a sampled sound. 1 plays it just
  79.      one time. Channel selects the soundchannel. Channel is a value between
  80.      zero and the number of allocated channels minus 1.
  81.  
  82.      If PlaySample was successful, it returns TRUE, else FALSE. More
  83.      detailed information on the error occur in IFF8SVXError.
  84.  
  85.      PlaySample() plays the sound with a second task, that feeds the
  86.      Audio-Device with the data it copies from Fast-memory to Chip-memory.
  87.      The memory-chunk copied each time is MaxChunkSize bytes big. IF
  88.      MaxChunkSize is too small, there can be some problems in timing.
  89.  
  90.      While you play a sound, your main programm can continue doing other
  91.      things. You can play different sounds on different channels at the
  92.      same time by calling PlaySample() several times. If you call
  93.      PlaySample with a channel that plays a sound at the moment, you will
  94.      replace the played by the new one immediately.
  95.  
  96.      It is possible to play the same sound on all channels at the same
  97.      time. Only high sampling rates and / or too small MaxChunkSizes can
  98.      cause small problems. There will be some `clicks' while you here your
  99.      sound.
  100.  
  101.      You are not allowed to deallocate a sounds memory with Dealloc8SVX()
  102.      while the sound is playing.
  103.  
  104.  
  105.                Wait for a sound to complete:
  106.              ---------------------------------
  107.  
  108.   PROCEDURE WaitPlay(Channel: CARDINAL);
  109.  
  110.      WaitPlay() waits for the sound played in Channel[Channel] to finish.
  111.      If you select IFF8SVXLoad.AllChannels as Channel, WaitPlay will wait
  112.      for all channels to finish.
  113.  
  114.      In fact, WaitPlay() returns a short time before a sound finishes.
  115.      There is just one more block of data to play. This enables you to play
  116.      a second sound directly after another sound without a pause.
  117.  
  118.  
  119.                 Close the Audio-Device:
  120.               ----------------------------
  121.  
  122.  
  123. PROCEDURE CloseAudio();
  124.  
  125.  
  126.      CloseAudio() closes the Audio-Device and stops the task that plays the
  127.      sounds. All playing sounds are stopped.
  128.  
  129.  
  130.              Information on Variables and Types:
  131.            ---------------------------------------
  132.  
  133.   IFF8SVXInfo:
  134.  
  135.      Data of a sampled sound is saved into variables of this type. It
  136.      contains a big RECORD, which has got many Sub-RECORDs.
  137.  
  138.      If you just want to play some sounds you won't have to know anything
  139.      about the contents of this variable.
  140.  
  141.    IFF8SVXInfo.loadedChunks is a SET, that contains Flags for each
  142.      Sub-RECORD. They are set if the Sub-RECORD contains legal (loaded)
  143.      data.
  144.  
  145.    IFF8SVXInfo.next/prev is unused. You can use it to link several
  146.      Sounds.
  147.  
  148.    IFF8SVXInfo.VHDR contains important information on the sound like
  149.      it's volume, size, samplerate etc.
  150.  
  151.    IFF8VSXInfo.NAME/COPY/AUTH/ANNO contain a pointer to a string and it's
  152.      size. The string is an ARRAY[0..999] OF CHAR, but there is just as
  153.      much memory allocated as needed.
  154.  
  155.    IFF8SVXInfo.ATAK/RLSE contain information on the duration and
  156.      volume of a sound's attack and release. PlaySample ignores
  157.      these RECORDs.
  158.  
  159.    IFF8SVXInfo.BODY contains the sounddata. Moreover, there is information
  160.      on whether there's just one block of data per Octave (MaxChunkSize=0),
  161.      whether the allocated memory is all chip-memory and on the biggest
  162.      chunk's size. There can be up to 8 Octaves saved here. For each Octave
  163.      there's a linked list of IFF8SVXLoad.DataChunk's, that each contain a
  164.      pointer to their data and the data's size.
  165.  
  166.   IFF8SVXError:
  167.  
  168.     Contains the last ErrorNumber (IFF8SVXErrs).
  169.  
  170.     Errors:
  171.       iff8OK                --> last command was successfully.
  172.       iff8OutOfMem          --> system ran out of memory.
  173.       iff8Openfailed        --> Dos.Open() didn't succeed. --> Dos.IOErr().
  174.       iff8Readfailed        --> Dos.Read() didn't succeed. --> Dos-IOErr().
  175.       iff8NoIFF             --> File is no IFF-sampled-Sound.
  176.       iff8NoChannel         --> There's no more free Soundchannel.
  177.       iff8OpenDevicefailed  --> OpenDevice() failed.
  178.  
  179.   More detailed information on the variables and types can be seen in the
  180.   definition module.
  181.  
  182.  
  183.             Example-Programs:
  184.           ---------------------
  185.  
  186.   - PlaySample: Loads and plays the sound selected by Shift-Click or given
  187.                 as an CLI-argument.
  188.  
  189.   - PlayAll:    Plays a sound like PlaySample does. If the sound
  190.                 contains several octaves, the 4 lowest one will be played
  191.                 simoultaneously.
  192.  
  193.   - PlayKey:    PlayKey has to be started like PlaySample. After it has
  194.                 loaded the sound you can play it with different sampling-
  195.                 rates by pressing different keys.
  196.  
  197.   - PlayKanon:  Plays a sample on all channels with 0.5s delay each.
  198.  
  199.   - PlayRep:    Repeats a sampled sound endless.
  200.  
  201.  
  202.                 Copyright:
  203.               --------------
  204.  
  205.      IFF8SVXLoad and it's demonstration-programs are Public Domain. They
  206.      are free to be copied and spread as long as you leave the author's
  207.      name in. Furthermore it's procedures are free to be imported by other
  208.      PD-Programs and spread this way.
  209.  
  210.      If you make any changes in the programs, you can add a :History. line
  211.      in the program's head and put your name and the date in, but you are
  212.      not allowed to remove my name.
  213.  
  214.      You are not allowed to make any profit with IFF8SVXLoad or changed
  215.      versions of IFF8SVXLoad without the author's permission!
  216.  
  217.      Donations are wellcome!
  218.  
  219.  
  220. ---  Fridtjof.
  221.